# Implementing partisan symmetry: Problems and paradoxes
This repository contains replication data and plots for `Implementing partisan symmetry: Problems and paradoxes`. This code runs on Mac OS, and requires at least two cores and 8GB of RAM. You should use the `conda` package manager to recreate our testing environment. If you do not have `conda` already installed, please follow [these directions](https://docs.conda.io/en/latest/miniconda.html) to do so; we used conda version `4.9.2` for our setup. Once conda is set up, please run `conda env create -f environment.yml` from the command line. To activate the environment, run `conda activate partisan-symmetry`. You will now have access to `gerrychain`, our MCMC redistricting library, as well as some other Python data analysis and visualization packages.

If you're having trouble setting up the environment through conda, the essential libraries you need are:
 * geopandas=0.8.2
 * gerrychain=0.2.14
 * ipython=7.22.0
 * jupyter=1.0.0
 * matplotlib=3.3.4
 * pandas=1.2.2
 * python=3.8.5
 * seaborn=0.11.1
 * tqdm=4.60.0

The repository is organized as follows:
 * The `jsons` folder contains demographic and electoral data for our three states (UT, TX, NC).
 * The `scripts` folder contains Python scripts that will generate ensembles of districting plans on each state. You can edit the scripts to generate your own test ensembles of a specified size. Your test ensembles will be stored in the `outputs` folder under, say, `outputs/UToutput`, and will overwrite the data used in the Paper.
   * To run our Markov Chain on (say) Utah, please navigate to the `scripts` folder from the command line and run `python ensembleUT.py`. It should take no more than 12 hours to finish. The other states should have similar running times, and can be run simultaneously from other Terminal windows, though may slow each other down if your computer has fewer than four cores.
 * To replicate the plots used in the Paper, please navigate to the `scripts` folder from the command line.
    * To generate Figures 1 and 2, please run `python generate_sv_curves.py` from the `scripts` folder. This will print to the Terminal the Partisan Gini and Mean-Median scores of the plans in Figs. 1 and 2, and save plots to the `plots/High_Res_Plots/` folder. The Partisan Bias score is not calculated, as it can be simply read off of the seats-votes curve.
    * To generate the plots in Figures 4-6, please run `python make_plots.py` from the `scripts` folder. This will use the data in the `outputs` folder to generate plots for UT, TX, and NC by default. It should take no more than 5 minutes and save plots to the `plots/High_Res_Plots/` folder.
    * The assignment files and partisan Gini scores for the NC maps shown in Figure 7 are stored while running `python ensembleNC.py` from the `scripts` folder. As the ensemble runs are stochastic, each ensemble may generate slightly different example maps. To generate the maps and view their partisan Gini scores, run `python generate_NC_examples.py` from the `scripts` folder. This will save the maps to the `plots/High_Res_Plots/` folder.
   * The CSV file `figure_mapping.csv` gives the mapping from files in `plots/High_Res_Plots/` to Figures in the Paper. It is not an injective mapping, as there are often multiple `PNG` files to a Figure. For example, the file `plots/High_Res_Plots/utahSEN16_[4, 4]_mm_seats.png` corresponds to the second-from-top histogram in Figure 4. 
 * You can use the `make_plots.ipynb` and `check_distinct_plans.ipynb` Jupyter notebooks to make different plots and further explore the data, if you wish. To do so, please run `jupyter notebook` from the command line, and then use the browser GUI to work through the notebooks.

All Python scripts and notebooks have further instructions and documentation regarding our workflow. Please feel free to reach out to [gabe.schoenbach@gmail.com](mailto:gabe.schoenbach@gmail.com) if you run into any issues.
